檔案上傳 ¶

在 Yii 中上傳檔案通常藉助 yii\web\UploadedFile，它將每個上傳的檔案封裝為一個 UploadedFile 物件。結合 yii\widgets\ActiveForm 和 模型，您可以輕鬆實作安全的檔案上傳機制。

建立模型 ¶

如同使用純文字輸入一樣，要上傳單個檔案，您需要建立一個模型類別，並使用模型的屬性來保存上傳的檔案實例。您還應該宣告一個驗證規則來驗證檔案上傳。例如：

namespace app\models;

use yii\base\Model;
use yii\web\UploadedFile;

class UploadForm extends Model
{
    /**
     * @var UploadedFile
     */
    public $imageFile;

    public function rules()
    {
        return [
            [['imageFile'], 'file', 'skipOnEmpty' => false, 'extensions' => 'png, jpg'],
        ];
    }
    
    public function upload()
    {
        if ($this->validate()) {
            $this->imageFile->saveAs('uploads/' . $this->imageFile->baseName . '.' . $this->imageFile->extension);
            return true;
        } else {
            return false;
        }
    }
}

在上面的程式碼中，imageFile 屬性用於保存上傳的檔案實例。它與一個 file 驗證規則關聯，該規則使用 yii\validators\FileValidator 來確保上傳的檔案具有 png 或 jpg 副檔名。upload() 方法將執行驗證並將上傳的檔案保存到伺服器上。

file 驗證器允許您檢查檔案副檔名、大小、MIME 類型等。請參閱 核心驗證器 章節以取得更多詳細資訊。

提示：如果您要上傳圖片，您可以考慮使用 image 驗證器來代替。image 驗證器透過 yii\validators\ImageValidator 實作，該驗證器驗證屬性是否接收到有效的圖片，然後可以使用 Imagine 擴充套件 來保存或處理該圖片。

渲染檔案輸入 ¶

接下來，在視圖中建立一個檔案輸入欄位

<?php
use yii\widgets\ActiveForm;
?>

<?php $form = ActiveForm::begin(['options' => ['enctype' => 'multipart/form-data']]) ?>

    <?= $form->field($model, 'imageFile')->fileInput() ?>

    <button>Submit</button>

<?php ActiveForm::end() ?>

重要的是要記住，您需要將 enctype 選項添加到表單中，以便可以正確上傳檔案。fileInput() 呼叫將渲染一個 <input type="file"> 標籤，該標籤將允許使用者選擇要上傳的檔案。

提示：自 2.0.8 版本起，當使用檔案輸入欄位時，fileInput 會自動將 enctype 選項添加到表單中。

連接設定 ¶

現在，在控制器動作中，編寫程式碼以連接模型和視圖，以實作檔案上傳

namespace app\controllers;

use Yii;
use yii\web\Controller;
use app\models\UploadForm;
use yii\web\UploadedFile;

class SiteController extends Controller
{
    public function actionUpload()
    {
        $model = new UploadForm();

        if (Yii::$app->request->isPost) {
            $model->imageFile = UploadedFile::getInstance($model, 'imageFile');
            if ($model->upload()) {
                // file is uploaded successfully
                return;
            }
        }

        return $this->render('upload', ['model' => $model]);
    }
}

在上面的程式碼中，當表單提交時，會呼叫 yii\web\UploadedFile::getInstance() 方法，將上傳的檔案表示為 UploadedFile 實例。然後，我們依靠模型驗證來確保上傳的檔案有效，並將檔案保存到伺服器上。

上傳多個檔案 ¶

您也可以一次上傳多個檔案，只需對前面小節中列出的程式碼進行一些調整即可。

首先，您應該調整模型類別，在 file 驗證規則中新增 maxFiles 選項，以限制允許上傳的最大檔案數量。將 maxFiles 設定為 0 表示同時可以上傳的檔案數量沒有限制。同時上傳的檔案最大數量也受到 PHP 指令 max_file_uploads 的限制，預設值為 20。upload() 方法也應該更新為逐一保存上傳的檔案。

namespace app\models;

use yii\base\Model;
use yii\web\UploadedFile;

class UploadForm extends Model
{
    /**
     * @var UploadedFile[]
     */
    public $imageFiles;

    public function rules()
    {
        return [
            [['imageFiles'], 'file', 'skipOnEmpty' => false, 'extensions' => 'png, jpg', 'maxFiles' => 4],
        ];
    }
    
    public function upload()
    {
        if ($this->validate()) { 
            foreach ($this->imageFiles as $file) {
                $file->saveAs('uploads/' . $file->baseName . '.' . $file->extension);
            }
            return true;
        } else {
            return false;
        }
    }
}

在視圖檔案中，您應該將 multiple 選項添加到 fileInput() 呼叫中，以便檔案上傳欄位可以接收多個檔案。您還需要將 imageFiles 更改為 imageFiles[]，以便將屬性值作為陣列提交

<?php
use yii\widgets\ActiveForm;
?>

<?php $form = ActiveForm::begin(['options' => ['enctype' => 'multipart/form-data']]) ?>

    <?= $form->field($model, 'imageFiles[]')->fileInput(['multiple' => true, 'accept' => 'image/*']) ?>

    <button>Submit</button>

<?php ActiveForm::end() ?>

最後，在控制器動作中，您應該呼叫 UploadedFile::getInstances() 而不是 UploadedFile::getInstance()，以將 UploadedFile 實例陣列分配給 UploadForm::imageFiles。

namespace app\controllers;

use Yii;
use yii\web\Controller;
use app\models\UploadForm;
use yii\web\UploadedFile;

class SiteController extends Controller
{
    public function actionUpload()
    {
        $model = new UploadForm();

        if (Yii::$app->request->isPost) {
            $model->imageFiles = UploadedFile::getInstances($model, 'imageFiles');
            if ($model->upload()) {
                // file is uploaded successfully
                return;
            }
        }

        return $this->render('upload', ['model' => $model]);
    }
}